react-nitro-ffigen 0.0.0-stage → 0.0.1-alpha.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Margelo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,237 @@
-# Temporary Holding Version
+# Static Hermes FFI generator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```mermaid
+flowchart TD
+    A["Yoga C headers"] -->|ffigen| B["native.ts — FFI wrappers"]
+    B -->|"shermes -emit-c"| C["yoga.c — wrappers translated into C"]
+    C -->|"C compiler"| D["Compiled bridge"]
+
+    E["Yoga C++ implementation"] -->|"C++ compiler"| F["Compiled Yoga"]
+
+    D --> G["Link into the app with the Hermes runtime"]
+    F --> G
+```
+
+A small Bun/TypeScript generator for selected functions in public C headers.
+Clang parses the header with the library's include paths, defines, and target
+flags. The generator emits TypeScript native bindings and public declarations.
+No Python, CastXML, or runtime FFI dependency is needed by the generator.
+
+V1 supports C scalar values, typedefs, named enums whose constants fit `int32_t`,
+and opaque pointers to structs/unions. Struct values, buffers, callbacks,
+variadics, and other unsupported selections fail generation with the function
+and type that need support. Only explicitly selected functions are generated.
+
+## Generate bindings
+
+Call `generateBindings` from Bun. Paths in `clangArgs` are relative to the working
+directory passed as its second argument:
+
+```ts
+import { generateBindings } from "react-nitro-ffigen";
+import type { BindingOptions } from "react-nitro-ffigen";
+
+const options = {
+  name: "layout",
+  header: "yoga/Yoga.h",
+  clangArgs: ["-I", "/absolute/path/to/yoga"],
+  functions: [
+    "YGNodeNew",
+    "YGNodeStyleSetWidth",
+    "YGNodeLayoutGetWidth",
+    "YGNodeFreeRecursive",
+  ],
+} satisfies BindingOptions;
+
+const files = await generateBindings(options, import.meta.dir);
+```
+
+The returned file map contains:
+
+| File                       | Purpose                                                        |
+| -------------------------- | -------------------------------------------------------------- |
+| `native.ts`                | Compile with Static Hermes; installs `globalThis.layout`       |
+| `native.d.ts`              | Target-specific global declaration for checking `native.ts`    |
+| `api.d.ts`                 | Exported application types, including distinct pointer types    |
+| `ffigen_layout_adapters.h` | C adapters that normalize enum parameters/results to `int32_t` |
+
+Shared Hermes declarations (`c_ptr`, the C scalar types, and `$SHBuiltin`) live
+once in `react-nitro-ffigen/hermes`. Generated `native.d.ts` files import those
+types automatically. The project containing generated bindings must have
+`react-nitro-ffigen` installed; targets do not copy or maintain Hermes types.
+
+Scalar and pointer calls use the original C prototypes through their public
+header. Enum adapters let the C compiler handle the actual enum ABI, including
+short enums, without assuming that all enums are C `int`. Constants come from
+Clang's evaluated AST, including declarations produced by macros. Typedef chains
+are resolved; mutable pointers can be used as const pointers, but not vice versa.
+Different struct/union handles are incompatible in the public TypeScript API.
+Boolean wrappers convert between JS booleans and Hermes' numeric `c_bool`.
+
+Generation completes before any output files are written. A missing function,
+unsupported selected type, or Clang failure does not silently omit a binding.
+`generateBindings(options, cwd)` returns the
+four files as a `Record<string, string>` without writing them. The required `cwd`
+sets Clang's working directory for relative paths; the generator leaves the
+parent process's working directory unchanged.
+
+Import public types from the generated `api.d.ts` module:
+
+```ts
+import type { YGNodeRef } from "./generated/api";
+
+const node: YGNodeRef = globalThis.layout.YGNodeNew();
+globalThis.layout.YGNodeFreeRecursive(node);
+```
+
+The type import also supplies the declaration for the runtime global. It does not
+load the compiled library; native initialization must evaluate the Hermes unit
+before application code runs. Public C types are module exports and require no
+global type namespace or triple-slash reference.
+
+## Native C adapters
+
+An adapter is a generated C wrapper that exposes a signature Hermes can call
+and invokes the original library function using its declared C types. Adapter
+implementations live in `src/adapters/`; they use the resolved binding descriptions
+in `src/binding-types.ts`, while `src/clang-ast-types.ts` describes Clang's input AST.
+
+The [enum adapter](src/adapters/enum.ts) handles functions with enum parameters
+or return values. Hermes can represent the numeric values, but mapping every C
+enum directly to `c_int` would assume its underlying integer type. Compiler flags
+such as `-fshort-enums` can change that type. Instead, the generated wrapper uses
+`int32_t` at the Hermes boundary (`c_i32` in the binding) and casts to/from the
+original enum. For example:
+
+```c
+static inline void ffigen_yoga_YGNodeStyleSetFlexDirection(
+    YGNodeRef node, int32_t direction) {
+  YGNodeStyleSetFlexDirection(node, (YGFlexDirection)direction);
+}
+```
+
+The C compiler handles the enum's actual calling convention. Compile the adapter
+with the same target and enum-related flags as the library. Generation rejects
+enum constants outside the signed 32-bit range so the adapter can preserve them.
+
+Future APIs may need other adapters, such as for structs passed or returned by
+value. Those require a concrete design for how JS supplies or reads the fields
+and how native storage is managed. Struct values currently remain unsupported;
+opaque struct pointers already work. Add a separate adapter when an API requires
+it, using the enum module as the first concrete implementation.
+
+## Compile and consume
+
+Check the native source separately from the application declarations:
+
+```sh
+bun packages/react-nitro-ffigen/src/tsc.ts generated/native.ts
+```
+
+The check extends `config/tsconfig.json`, selects the supplied files, and disables
+emission and composite builds. The build pipeline and generator tests use this
+same check.
+
+Compile it using the pinned Hermes compiler:
+
+```sh
+packages/react-nitro-hermes/.build/hermes-cmake/bin/shermes \
+  -typed -parse-flow -O -emit-c -exported-unit=layout \
+  -o generated/layout.c generated/native.ts
+```
+
+Compile that C with the generated directory, library headers, and matching Hermes
+headers on the include path. Link it with the native library and Hermes, then
+load it with `evaluateSHUnit(sh_export_layout)`, as the Yoga integration does.
+
+Import public types from `api.d.ts` in application code. The loaded unit supplies
+the runtime object:
+
+```ts
+import type { YGNodeRef } from "./generated/api";
+const node: YGNodeRef = globalThis.layout.YGNodeNew();
+globalThis.layout.YGNodeStyleSetWidth(node, 50);
+globalThis.layout.YGNodeFreeRecursive(node);
+```
+
+Do not include `native.ts` or `native.d.ts` in that app project, or send the native
+source through a bundler that erases its annotations. The generated source uses
+the shared TypeScript/Flow syntax supported by the pinned compiler. Ambient
+declarations are separate because `shermes` does not execute them.
+
+Use the same library version, target, SDK, and preprocessor flags for generation
+and native compilation. Generate separately for different target ABIs; typedefs
+such as `size_t` are resolved for the target passed to Clang. `clang` can be
+overridden in the config.
+
+This is a low-level API: ownership and freeing remain explicit. Handles are opaque
+native values, not JS objects with fields or numeric addresses to manipulate.
+No nullability, error-code, lifetime, or garbage-collection policy is inferred.
+Integer values use JS numbers and Hermes' conversions, so full-range 64-bit
+integers are not supported. Enums accept their declared values; arbitrary bitmask
+combinations need a future API-specific policy. No struct layout offsets or
+general macro constants are generated.
+
+## Yoga package (macOS)
+
+The shared builder in `src/build.ts` generates and checks bindings, builds a
+native CMake target, and emits an exported Static Hermes C unit. A target's
+`ffi.config.ts` uses the `TargetConfig` type from `react-nitro-ffigen/build` and
+extends the binding config with its native build settings:
+
+```ts
+native: {
+  sourceDir: 'yoga/yoga',
+  target: 'yogacore',
+},
+```
+
+Paths are relative to the config directory. Invoke the builder with any config:
+
+```sh
+bun packages/react-nitro-ffigen/src/build.ts packages/react-nitro-yoga/ffi.config.ts
+```
+
+The [React Nitro Yoga package](../react-nitro-yoga/README.md) owns its pinned
+`yoga` submodule, `ffi.config.ts`, Swift package, and generated bindings. New
+libraries can use this generator from their own packages.
+
+Initialize the submodules and build from the repository root:
+
+```sh
+git submodule update --init --recursive
+bun install
+```
+
+The root postinstall runs workspace builds in dependency order, building the
+pinned compiler in `react-nitro-hermes` before generating and compiling Yoga
+in `react-nitro-yoga`. To rebuild only Yoga, run
+`bun run --cwd packages/react-nitro-yoga build`. Native builds are incremental;
+standalone target builds require an existing compiler.
+Yoga outputs are under `packages/react-nitro-yoga/Generated/`, with the host
+native library at `packages/react-nitro-yoga/.build/yoga/libyogacore.a`.
+
+Import Yoga's public types from `react-nitro-yoga`:
+
+```ts
+import type { YGNodeRef } from "react-nitro-yoga";
+
+const node: YGNodeRef = globalThis.yoga.YGNodeNew();
+globalThis.yoga.YGNodeFreeRecursive(node);
+```
+
+Declare `react-nitro-yoga` as a dependency of consumers. Its Swift package
+exposes native `Yoga` separately from `ReactNitroYoga`, which initializes the
+compiled unit in each runtime. The renderer consumes native Yoga and the public
+types; runtime creation calls the initializer in `react-nitro-yoga`.
+
+## Checks
+
+```sh
+bun run --cwd packages/react-nitro-ffigen typecheck
+bun run --cwd packages/react-nitro-ffigen test
+```
+
+Tests check public pointer/const/enum types, compile multiple targets using the
+shared Hermes declarations, execute C enum adapters under `-fshort-enums`, and
+verify that unsupported APIs and Clang errors are reported.

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "react-nitro-ffigen",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-alpha.7",
+  "dependencies": {
+    "react-nitro-hermes": "0.0.1-alpha.7",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": {
+    "tag": "latest",
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/generate.ts",
+    "./hermes": {
+      "types": "./src/hermes.d.ts"
+    },
+    "./build": "./src/build.ts",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/margelo/react-nitro.git",
+    "directory": "packages/react-nitro-ffigen"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/adapters/enum.ts

@@ -0,0 +1,48 @@
+import type { FunctionBinding } from '../binding-types';
+
+interface EnumAdapter {
+  symbol: string;
+  lines: string[];
+}
+
+/**
+ * Generate a C wrapper when a function takes or returns an enum.
+ *
+ * Hermes represents our enum values as c_i32, but a C enum's underlying integer
+ * type depends on the target and compiler flags (for example, -fshort-enums).
+ * The wrapper exposes int32_t to Hermes and casts to/from the declared C types.
+ * Compiling it with the library's headers and flags lets the C compiler handle
+ * the actual enum ABI. Type resolution rejects constants outside int32_t range.
+ * Functions without enum parameters or results need no enum adapter.
+ */
+export function generateEnumAdapter(
+  binding: FunctionBinding,
+  targetName: string,
+): EnumAdapter | undefined {
+  const hasEnumParameter = binding.parameters.some(parameter => parameter.type.kind === 'enum');
+  const needsAdapter = binding.result.kind === 'enum' || hasEnumParameter;
+  if (needsAdapter === false) return undefined;
+
+  const symbol = `ffigen_${targetName}_${binding.name}`;
+  const cParameters: string[] = [];
+  const cArguments: string[] = [];
+  for (const { name, type } of binding.parameters) {
+    const cType = type.kind === 'enum' ? 'int32_t' : type.c;
+    cParameters.push(`${cType} ${name}`);
+    cArguments.push(`(${type.c})${name}`);
+  }
+
+  const { result } = binding;
+  const cResult = result.kind === 'enum' ? 'int32_t' : result.c;
+  const cParams = cParameters.length === 0 ? 'void' : cParameters.join(', ');
+  const cArgs = cArguments.join(', ');
+  const cCall = `${binding.name}(${cArgs})`;
+  const statement = result.kind === 'void' ? `${cCall};` : `return (${cResult})${cCall};`;
+  const lines = [
+    `static inline ${cResult} ${symbol}(${cParams}) {`,
+    `  ${statement}`,
+    '}',
+    '',
+  ];
+  return { symbol, lines };
+}

package/src/binding-types.ts

@@ -0,0 +1,18 @@
+/** Resolved binding descriptions shared by the generator and C adapters. */
+export interface Type {
+  kind: 'scalar' | 'boolean' | 'pointer' | 'enum' | 'void';
+  native: string;
+  public: string;
+  c: string;
+}
+
+export interface Parameter {
+  name: string;
+  type: Type;
+}
+
+export interface FunctionBinding {
+  name: string;
+  parameters: Parameter[];
+  result: Type;
+}

package/src/build.ts

@@ -0,0 +1,98 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { hermesBuildDirectory as hermesBuild, shermesPath as compiler } from 'react-nitro-hermes';
+import { generateBindings } from './generate';
+import type { BindingConfig } from './generate';
+import { tscPath as tsc, typecheck } from './tsc';
+
+/**
+ * This build script takes a target's ffigen configuration and builds the corresponding native library and TypeScript bindings.
+ * It's the build step for "turning a native library expsed by a C header into TypeScript bindings, using shermes ffi".
+ */
+
+export interface TargetConfig extends BindingConfig {
+  native: {
+    /** CMake source directory, relative to the config file. */
+    sourceDir: string;
+    /** CMake target that builds the native library. */
+    target: string;
+  };
+}
+
+export async function run(command: string[], cwd?: string): Promise<void> {
+  const child = Bun.spawn(command, { cwd, stdout: 'inherit', stderr: 'inherit' });
+  const code = await child.exited;
+  if (code !== 0) throw new Error(`${command[0]} exited with status ${code}`);
+}
+
+export async function buildTarget(configPath: string) {
+  // Prepare all paths:
+  const path = resolve(configPath);
+  const url = pathToFileURL(path);
+  const module = await import(url.href);
+  const config: TargetConfig = module.default;
+  const targetDirectory = dirname(path);
+  const nativeSource = resolve(targetDirectory, config.native.sourceDir);
+  const cmakeFile = join(nativeSource, 'CMakeLists.txt');
+  try {
+    await access(cmakeFile);
+  } catch {
+    throw new Error(`Cannot read ${cmakeFile}. Initialize target submodules with git submodule update --init --recursive`);
+  }
+  try {
+    await access(compiler);
+  } catch {
+    throw new Error(`Shermes compiler not found at ${compiler}. Run bun run --cwd packages/react-nitro-hermes build from the repository root`);
+  }
+  const directory = resolve(targetDirectory, '.build');
+  const generated = resolve(targetDirectory, config.outDir);
+  const nativeBuild = join(directory, config.name);
+
+  // Step 1: compile the actual native library (for example yoga):
+  // Configure a Release build of the target's native library using Ninja.
+  await run(['cmake', '-S', nativeSource, '-B', nativeBuild, '-G', 'Ninja', '-DCMAKE_BUILD_TYPE=Release']);
+  // Compile the configured native library
+  await run(['cmake', '--build', nativeBuild, '--target', config.native.target, '--parallel', '8']);
+
+  // Step 2: Generate the TypeScript bindings from the C header:
+  const files = await generateBindings(config, targetDirectory);
+  await mkdir(generated, { recursive: true });
+  const entries = Object.entries(files);
+  for (const [name, contents] of entries) {
+    const path = join(generated, name);
+    await writeFile(path, contents);
+  }
+  const nativePath = join(generated, 'native.ts');
+  // Type-check the generated FFI wrappers without emitting JavaScript.
+  await typecheck([nativePath]);
+
+  // Step 3: Turn typescript bindings into shermes C code:
+  const nativeC_OutputPath = join(generated, `${config.name}.c`);
+  const relativeNativeC = relative(targetDirectory, nativeC_OutputPath);
+  const relativeNativePath = relative(targetDirectory, nativePath);
+  // Emit the optimized FFI wrappers as an exported C unit for native compilation.
+  await run([
+    compiler, '-typed', '-parse-flow', '-O', '-g0', '-emit-c', `-exported-unit=${config.name}`,
+    '-o', relativeNativeC, relativeNativePath,
+  ], targetDirectory);
+  console.log(`${config.name} target built in ${directory}`);
+
+  // The platform build pipeline will integrate the shermes c code into the final build
+  return { compiler, directory, generated, hermesBuild, nativePath, tsc, nativeBuild };
+}
+
+if (import.meta.main) {
+  const argument = process.argv[2];
+  if (argument === undefined || process.argv.length !== 3) {
+    console.error('Usage: bun packages/react-nitro-ffigen/src/build.ts path/to/ffi.config.ts');
+    process.exit(1);
+  }
+  try {
+    await buildTarget(argument);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+  }
+}

package/src/clang-ast-types.ts

@@ -0,0 +1,16 @@
+/**
+ * The subset of Clang's `-ast-dump=json` output consumed by the generator.
+ * These types describe the parsed C declarations.
+ */
+export interface AstType {
+  qualType: string;
+}
+
+export interface AstNode {
+  kind: string;
+  name?: string;
+  type?: AstType;
+  inner?: AstNode[];
+  value?: string;
+  variadic?: boolean;
+}

package/src/generate.ts

@@ -0,0 +1,346 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { generateEnumAdapter } from './adapters/enum';
+import type { FunctionBinding, Parameter, Type } from './binding-types';
+import type { AstNode } from './clang-ast-types';
+
+/**
+ * The main generator that turns a c header into TypeScript bindings.
+ */
+
+export interface BindingOptions {
+  /** C include spelling, for example yoga/Yoga.h. */
+  header: string;
+  /** Global object installed by the compiled Hermes unit. */
+  name: string;
+  /** Explicit public function allowlist. Unsupported selections are errors. */
+  functions: string[];
+  /** Include paths, defines, target and SDK flags for the actual library build. */
+  clangArgs?: string[];
+  clang?: string;
+}
+
+export interface BindingConfig extends BindingOptions {
+  outDir: string;
+}
+
+// Map of c-scalar types to shermes ffi type names
+const nativeTypes = new Map([
+  ['char', 'c_char'],
+  ['signed char', 'c_schar'],
+  ['unsigned char', 'c_uchar'],
+  ['short', 'c_short'],
+  ['unsigned short', 'c_ushort'],
+  ['int', 'c_int'],
+  ['unsigned int', 'c_uint'],
+  ['long', 'c_long'],
+  ['unsigned long', 'c_ulong'],
+  ['long long', 'c_longlong'],
+  ['unsigned long long', 'c_ulonglong'],
+  ['float', 'c_float'],
+  ['double', 'c_double'],
+]);
+
+function identifier(value: string): void {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) return;
+  throw new Error(`Invalid identifier: ${value}`);
+}
+
+function constantValue(node: AstNode): string | undefined {
+  if (node.kind === 'ConstantExpr' && node.value !== undefined) {
+    return node.value;
+  }
+  for (const child of node.inner ?? []) {
+    const value = constantValue(child);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function wrapperType(type: Type): string {
+  switch (type.kind) {
+    case 'pointer': return 'c_ptr';
+    case 'boolean': return 'boolean';
+    case 'void': return 'void';
+    default: return 'number';
+  }
+}
+
+/**
+ * To parse a library's C header we use clang, which gives us a structured JSON representation.
+ */
+async function parseHeader(options: BindingOptions, cwd: string): Promise<AstNode> {
+  if (/^[A-Za-z0-9_./+-]+$/.test(options.header) === false) {
+    throw new Error('header must be a C include path without quotes or newlines');
+  }
+  const temporaryRoot = tmpdir();
+  const prefix = join(temporaryRoot, 'shermes-ffigen-');
+  const directory = await mkdtemp(prefix);
+  try {
+    // We create a temporary c file that include's the library's header
+    const input = join(directory, 'input.c');
+    await writeFile(input, `#include <${options.header}>\n`);
+    // We use clang to get an AST dump of the library's header file
+    const command = [
+      options.clang ?? 'clang', '-x', 'c', '-std=c11',
+      ...options.clangArgs ?? [],
+      '-Xclang', '-ast-dump=json', '-fsyntax-only', input,
+    ];
+    const process = Bun.spawn(command, { cwd, stdout: 'pipe', stderr: 'pipe' });
+    const output = new Response(process.stdout);
+    const errors = new Response(process.stderr);
+    const [stdout, stderr, exitCode] = await Promise.all([
+      output.text(), errors.text(), process.exited,
+    ]);
+    if (exitCode !== 0) {
+      throw new Error(`Clang could not parse ${options.header}:\n${stderr}`);
+    }
+    return JSON.parse(stdout) as AstNode;
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+export async function generateBindings(
+  options: BindingOptions,
+  cwd: string,
+): Promise<Record<string, string>> {
+  identifier(options.name);
+  if (options.functions.length === 0) {
+    throw new Error('Select at least one function');
+  }
+  const selected = new Set(options.functions);
+  if (selected.size !== options.functions.length) {
+    throw new Error('The function allowlist contains duplicates');
+  }
+  const ast = await parseHeader(options, cwd);
+  const declarations = new Map<string, AstNode>();
+  const enums = new Map<string, AstNode>();
+  const typedefs = new Map<string, AstNode>();
+  for (const node of ast.inner ?? []) {
+    if (node.name === undefined) continue;
+    if (node.kind === 'FunctionDecl') declarations.set(node.name, node);
+    if (node.kind === 'TypedefDecl') typedefs.set(node.name, node);
+    if (node.kind === 'EnumDecl') enums.set(node.name, node);
+  }
+
+  const publicTypes = new Map<string, string>();
+  const constants = new Map<string, string>();
+
+  function resolveType(spelling: string, visiting = new Set<string>()): Type {
+    const trimmed = spelling.trim();
+    // Top-level const has no effect for scalar values passed by value.
+    const name = trimmed.endsWith('*') ? trimmed : trimmed.replace(/^const /, '');
+    const native = nativeTypes.get(name);
+    if (native !== undefined) {
+      return { kind: 'scalar', native, public: 'number', c: spelling };
+    }
+    if (name === '_Bool' || name === 'bool') {
+      return { kind: 'boolean', native: 'c_bool', public: 'boolean', c: spelling };
+    }
+    if (name === 'void') {
+      return { kind: 'void', native: 'void', public: 'void', c: spelling };
+    }
+    const typedef = typedefs.get(name);
+    if (typedef?.type !== undefined) {
+      if (visiting.has(name)) throw new Error(`Recursive typedef: ${name}`);
+      visiting.add(name);
+      const resolved = resolveType(typedef.type.qualType, visiting);
+      if (resolved.public !== name) publicTypes.set(name, resolved.public);
+      return { ...resolved, public: name, c: spelling };
+    }
+    const pointer = /^(const )?(struct|union) ([A-Za-z_][A-Za-z0-9_]*) \*$/.exec(name);
+    if (pointer !== null) {
+      const record = `${pointer[2]} ${pointer[3]}`;
+      const constant = pointer[1] === undefined ? 'false' : 'boolean';
+      const publicType = `Pointer<"${record}", ${constant}>`;
+      return { kind: 'pointer', native: 'c_ptr', public: publicType, c: spelling };
+    }
+    if (name.startsWith('enum ')) {
+      const enumName = name.slice(5);
+      const enumeration = enums.get(enumName);
+      if (enumeration === undefined) throw new Error(`Incomplete enum: ${name}`);
+      const values: string[] = [];
+      let next = 0n;
+      for (const member of enumeration.inner ?? []) {
+        if (member.kind !== 'EnumConstantDecl' || member.name === undefined) continue;
+        const explicit = constantValue(member);
+        const value = explicit === undefined ? next : BigInt(explicit);
+        // The enum adapter exposes int32_t to Hermes; every constant must fit.
+        if (value < -2147483648n || value > 2147483647n) {
+          throw new Error(`Enum ${enumName} exceeds the supported signed 32-bit range`);
+        }
+        const text = value.toString();
+        constants.set(member.name, text);
+        values.push(text);
+        next = value + 1n;
+      }
+      if (values.length === 0) throw new Error(`Empty enum: ${enumName}`);
+      const unique = new Set(values);
+      const literals = [...unique];
+      const publicType = literals.join(' | ');
+      publicTypes.set(enumName, publicType);
+      return { kind: 'enum', native: 'c_i32', public: enumName, c: spelling };
+    }
+    throw new Error(`Unsupported C type "${spelling}"; v1 supports scalars, enums and opaque struct/union pointers`);
+  }
+
+  const functions: FunctionBinding[] = [];
+  for (const name of options.functions) {
+    identifier(name);
+    const declaration = declarations.get(name);
+    if (declaration?.type === undefined) throw new Error(`Function not found: ${name}`);
+    const signature = declaration.type.qualType;
+    if (declaration.variadic || signature.includes('...')) {
+      throw new Error(`${name}: variadic functions are not supported`);
+    }
+    if (signature.endsWith('()')) {
+      throw new Error(`${name}: a full C function prototype is required`);
+    }
+    if (signature.includes('__attribute__')) {
+      throw new Error(`${name}: attributed calling conventions are not supported`);
+    }
+    const opening = signature.indexOf('(');
+    if (opening < 0 || signature.includes('(*')) {
+      throw new Error(`${name}: unsupported function signature ${signature}`);
+    }
+    const resultSpelling = signature.slice(0, opening);
+    try {
+      const result = resolveType(resultSpelling);
+      const parameters: Parameter[] = [];
+      for (const parameter of declaration.inner ?? []) {
+        if (parameter.kind !== 'ParmVarDecl' || parameter.type === undefined) continue;
+        const parameterName = parameter.name ?? `arg${parameters.length}`;
+        const type = resolveType(parameter.type.qualType);
+        parameters.push({ name: `_${parameterName}`, type });
+      }
+      functions.push({ name, parameters, result });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`${name}: ${message}`);
+    }
+  }
+
+  const source: string[] = [
+    '// Generated by react-nitro-ffigen. Do not edit.',
+    '/// <reference path="./native.d.ts" />',
+    '"use strict";',
+    '',
+  ];
+  const nativeApi: string[] = [];
+  const publicApi: string[] = [];
+  const adapterName = `ffigen_${options.name}_adapters.h`;
+  const adapters = [
+    '// Generated by react-nitro-ffigen. Do not edit.',
+    '#pragma once',
+    '#include <stdint.h>',
+    `#include <${options.header}>`,
+    '',
+  ];
+  const body = ['(function () {'];
+  const exported: string[] = [];
+
+  for (const binding of functions) {
+    const adapter = generateEnumAdapter(binding, options.name);
+    let symbol = binding.name;
+    let include = options.header;
+    if (adapter !== undefined) {
+      symbol = adapter.symbol;
+      include = adapterName;
+      adapters.push(...adapter.lines);
+    }
+    const index = exported.length;
+    const nativeParameters: string[] = [];
+    const wrapperParameters: string[] = [];
+    const publicParameters: string[] = [];
+    const argumentsList: string[] = [];
+    const conversions: string[] = [];
+    for (const parameter of binding.parameters) {
+      const { name, type } = parameter;
+      nativeParameters.push(`${name}: ${type.native}`);
+      const parameterType = wrapperType(type);
+      wrapperParameters.push(`${name}: ${parameterType}`);
+      publicParameters.push(`${name}: ${type.public}`);
+      if (type.kind === 'boolean') {
+        const converted = `nativeArg${argumentsList.length}`;
+        conversions.push(`    const ${converted} = ${name} ? 1 : 0;`);
+        argumentsList.push(converted);
+      } else {
+        argumentsList.push(name);
+      }
+    }
+    const nativeParams = nativeParameters.join(', ');
+    const wrapperParams = wrapperParameters.join(', ');
+    const publicParams = publicParameters.join(', ');
+    const argumentsText = argumentsList.join(', ');
+    const { result } = binding;
+    const wrapperResult = wrapperType(result);
+    nativeApi.push(`    ${binding.name}: (${wrapperParams}) => ${wrapperResult};`);
+    publicApi.push(`  ${binding.name}(${publicParams}): ${result.public};`);
+    body.push(
+      `  const native_${index} = $SHBuiltin.extern_c(`,
+      `    { include: "${include}" },`,
+      `    function ${symbol}(${nativeParams}): ${result.native} { throw 0; },`,
+      '  );',
+      `  function call_${index}(${wrapperParams}): ${wrapperResult} {`,
+      ...conversions,
+    );
+    const call = `native_${index}(${argumentsText})`;
+    if (result.kind === 'boolean') {
+      body.push(`    const result = ${call};`, '    return result !== 0;');
+    } else if (result.kind === 'void') {
+      body.push(`    ${call};`);
+    } else {
+      body.push(`    return ${call};`);
+    }
+    body.push('  }', '');
+    exported.push(`${binding.name}: call_${index}`);
+  }
+  for (const [name, value] of constants) {
+    if (selected.has(name)) throw new Error(`Enum constant conflicts with function: ${name}`);
+    nativeApi.push(`    ${name}: number;`);
+    publicApi.push(`  readonly ${name}: ${value};`);
+    exported.push(`${name}: ${value}`);
+  }
+  const exportList = exported.join(', ');
+  source.push(...body);
+  source.push(`  globalThis.${options.name} = { ${exportList} };`, '})();', '');
+  const types = [
+    '// Generated public types. Import in the app, not the native compilation.',
+    'declare const pointer: unique symbol;',
+    'type Pointer<Record extends string, Const extends boolean> = {',
+    '  readonly [pointer]: readonly [Record, Const];',
+    '};',
+    '',
+  ];
+  for (const [name, type] of publicTypes) types.push(`export type ${name} = ${type};`);
+  types.push(
+    '',
+    'export interface API {',
+    ...publicApi,
+    '}',
+    '',
+    'declare global {',
+    `  var ${options.name}: API;`,
+    '}',
+    '',
+  );
+  const nativeDeclaration = [
+    '// Generated native API types. Include only when checking native.ts.',
+    'import type {} from "react-nitro-ffigen/hermes";',
+    '',
+    'declare global {',
+    `  var ${options.name}: {`,
+    ...nativeApi,
+    '  };',
+    '}',
+    '',
+  ];
+  return {
+    'native.ts': source.join('\n'),
+    'api.d.ts': types.join('\n'),
+    'native.d.ts': nativeDeclaration.join('\n'),
+    [adapterName]: adapters.join('\n'),
+  };
+}

package/src/hermes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * shermes only works properly with flow typed files, however, we want to consume the binding JS code
+ * as properly typed TypeScript definitions.
+ * This provides definitions currently missing in shermes.
+ */
+export {};
+
+declare global {
+  type c_char = number;
+  type c_schar = number;
+  type c_uchar = number;
+  type c_short = number;
+  type c_ushort = number;
+  type c_int = number;
+  type c_uint = number;
+  type c_long = number;
+  type c_ulong = number;
+  type c_longlong = number;
+  type c_ulonglong = number;
+  type c_float = number;
+  type c_double = number;
+  type c_bool = number;
+  type c_i32 = number;
+  const nativePointer: unique symbol;
+  type c_ptr = { readonly [nativePointer]: true };
+
+  const $SHBuiltin: {
+    extern_c<T extends (...args: any[]) => any>(
+      options: { include: string },
+      signature: T,
+    ): T;
+  };
+}

package/src/tsc.ts

@@ -0,0 +1,52 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import typescript from 'typescript/package.json';
+
+const packageURL = import.meta.resolve('typescript/package.json');
+const executableURL = new URL(typescript.bin.tsc, packageURL);
+export const tscPath = fileURLToPath(executableURL);
+
+export async function typecheck(sources: string[]): Promise<void> {
+  const files: string[] = [];
+  for (const source of sources) {
+    const path = resolve(source);
+    files.push(path);
+  }
+  const baseConfig = resolve(import.meta.dir, '../../../config/tsconfig.json');
+  const root = tmpdir();
+  const prefix = join(root, 'ffigen-tsconfig-');
+  const directory = await mkdtemp(prefix);
+  try {
+    const config = {
+      extends: baseConfig,
+      compilerOptions: { composite: false, noEmit: true },
+      files,
+      include: [],
+    };
+    const contents = JSON.stringify(config, null, 2);
+    const project = join(directory, 'tsconfig.json');
+    await writeFile(project, contents);
+    const child = Bun.spawnSync([process.execPath, tscPath, '--project', project], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    if (child.exitCode !== 0) {
+      const output = child.stdout.toString();
+      const errors = child.stderr.toString();
+      throw new Error(`TypeScript checking failed:\n${output}${errors}`);
+    }
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.main) {
+  const sources = process.argv.slice(2);
+  if (sources.length === 0) {
+    console.error('Usage: bun packages/react-nitro-ffigen/src/tsc.ts <source.ts> [...]');
+    process.exit(1);
+  }
+  await typecheck(sources);
+}